====== buttonToPage() ======

''string **buttonToPage**(string //Seite//, [mixed //Beschriftung//, mixed //Platzhalter//, mixed //CSS-Klasse//])''

Mit dieser Funktion können Knöpfe erstellt werden, um innerhalb des Fragebogens zu navigieren. Die Funktion gibt den HTML-Code für den Knopf zurück und speichert diesen (optional) in einem Platzhalter, z.B. zur Verwendung im [[:de:create:layout|Layout]].

  * //Seite//\\ Kennung der Fragebogen-Seite zu der gesprungen werden soll.
    * <[[:de:glossary#seitenkennung|Seiten-Kennung]]> -- Sprung zu einer bestimmten Seite im Fragebogen
    * '''end''' -- Sprung zur letzten Seite (Ende der Befragung)
  * //Beschrifung//\\ Die Beschriftung des Knopfes (Text oder HTML-Code). Wird keine Beschriftung angegeben, so verwendet der Knopf eine für die Fragebogen-Seite eingetragene Notiz oder die Seiten-Kennung.
    * <string> -- Beschriftung unabhängig von der Sprachversion
    * <array> -- Beschriftung je nach Sprachversion. Die Kennung der Sprachversion (z.B. ''"ger"'' oder ''"eng"'') wird als Schlüssel des Arrays verwendet, die eigentliche Beschriftung als zugehöriger Wert.
  * //Platzhalter//\\ Wird als dritter Parameter ein Platzhalter oder ''true'' angegeben, so bleibt der Knopf im gesamten Fragebogen gültig, sonst nur auf der aktuellen Fragebogen-Seite.
    * <[[:de:create:placeholders#regeln_fuer_benutzerdefinierte_platzhalter|Platzhalter]]> -- Der HTML-Code für den Knopf wird im angegeben Platzhalter abgelegt und kann damit z.B. auch im Layout verwendet werden.
    * ''true'' -- Der Knopf ist im gesamten Fragebogen gültig, der HTML-Code muss aber manuell eingebunden werden.
    * ''null'' oder ''false'' -- Der Knopf ist nur auf der aktuellen Seite des Fragebogens gültig.
  * //CSS-Klasse//\\ Dem ''<button>''-Tag, welches für den Knopf verwendet wird, können neben der CSS-Klasse ''buttonToPage'' noch weitere CSS-Klassen als String oder Array beigefügt werden. So lässt sich z.B. eine hierarchische Navigation realisieren.


===== Mehrere Seiten zurück springen =====

Der Teilnehmer soll die Möglichkeit haben, zu einer früheren Seite zu springen.

Geben Sie der Seite, zu welcher der Teilnehmer springen soll, z.B. die Kennung "early" ([[:de:glossary#seitenkennung|Seiten-Kennung]]).

Fügen Sie an der Stelle, wo der Knopf erscheinen soll, folgenden PHP-Code ein ([[:de:create:php]])

<code php>
html(
  '<div style="text-align: center; margin: 2em 0">'.
  buttonToPage('early', 'Zurück zur Auswahl').
  '</div>'
);
</code>

Das ''<div>''-Tag sorgt dafür, dass der Knopf in einer eigenen Zeile und mit ein wenig Abstand nach oben und unten angezeigt wird.


===== Einfache Navigation =====

Der Teilnehmer soll während der gesamten Befragung die Möglichkeit haben, zu zwei bestimmten Seiten im Fragebogen zu springen.

Geben Sie den beiden Seiten im Fragebogen dafür zunächst Seiten-Kennungen, z.B. "jump1" und "jump2".

Fügen Sie auf der ersten Seite des Fragebogens folgenden PHP-Code ein:

<code php>
buttonToPage('jump1', 'Zur Auswahl', '%btnJ1%');
buttonToPage('jump2', 'Zur Übersicht', '%btnJ2%');
</code>

Fügen Sie in der HTML-Vorlage des Layouts ([[:de:create:layout]]) an geeigneter Stelle (z.B. links in der Navigation, sofern im Layout vorhanden, oder über den Platzhaltern für den Weiter-Knopf) folgenden HTML-Code ein.

<code html>
<div style="margin: 2em 0">
  <div>%btnJ1%</div>
  <div>%btnJ2%</div>
</div>
</code>

**Hinweis:** Die Knöpfe werden nur angezeigt, wenn der Fragebogen ab der ersten Seite gestartet wird. Falls Sie den Fragebogen testweise auf einer späteren Seite starten, werden nur die Platzhalter angezeigt.



===== Bearbeiten früherer Abschnitte =====

Wieder sollen im Layout mehrere Knöpfe angeboten werden, um innerhalb des Fragebogens zu navigieren. Allerdings soll ein Sprung nur zu den Kapiteln erlaubt sein, welche der Teilnehmer bereits regulär erreicht hat.

Geben Sie den Seiten, auf welchen die Kapitel beginnen, eindeutige Seiten-Kennungen, z.B. "chapter1" bis "chapter4".

Initialisieren Sie mit folgendem PHP-Code Platzhalter für alle Knöpfe (z.B. "%btnC1%" bis "%btnC5%"). Der IF-Filter mit ''[[:de:create:functions:getroute]]'' stellt sicher, dass die Knöpfe für einmal erreichte Kapitel auch dann erhalten bleiben, wenn der Teilnehmer die erste Seite erneut aufruft.

<code php>
if (getRoute() == 'start') {
  replace('%btnC1%', '');
  replace('%btnC2%', '');
  replace('%btnC3%', '');
  replace('%btnC4%', '');
  replace('%btnC5%', '');
}
</code>

Auf allen 5 Kapitel-Seiten, ab wo der jeweilige Knopf erscheinen soll, fügen Sie folgenden PHP-Code ein. Die Parameter müssen natürlich an die Seite angepasst werden.

<code php>
buttonToPage('chapter1', 'Kapitel 1', '%btnC1%');
</code>

In der HTML-Vorlage des Layouts fügen Sie wieder Platzhalter für die Knöpfe ein:

<code html>
<!-- Knöpfe untereinander -->
<div style="margin: 2em 0">
  <div>%btnC1%</div>
  <div>%btnC2%</div>
  <div>%btnC3%</div>
  <div>%btnC4%</div>
  <div>%btnC5%</div>
</div>
<!-- Knöpfe nebeneinander -->
<div style="margin: 2em 0">
  %btnC1%
  %btnC2%
  %btnC3%
  %btnC4%
  %btnC5%
</div>
</code>


===== Nicht-lineares Ausfüllen =====

Der Fragebogen soll nicht (unbedingt) linear bearbeitet werden? Mit ''buttonToPage()'' lässt sich auch eine umfangreiche Navigation realisieren.

Als Vorbereitung geben Sie allen Seiten, auf denen ein Abschnitt beginnt, unter **Fragebogen zusammenstellen** eine [[de:glossary#seitenkennung|Seiten-Kennung]] und tragen Sie als Kommentar für die Seite einen Titel für den Abschnitt ein, wie er in der Navigation erscheinen soll.

Es gibt zwei Möglichkeiten, die Navigation auf allen Seiten anzuzeigen:

  - Verwenden Sie Platzhalter und verwenden Sie diese direkt im **Fragebogen-Layout** -> //HTML-Vorlage// vor dem Platzhalter ''%questionnaire%'' -- dann muss der PHP-Code mit ''buttonToPage()'' nur einmal auf der ersten Seite des Fragebogens platziert werden, aber die aktuelle Seite kann bei dieser Lösung nicht farblich hervorgehoben werden.
  - Platzieren Sie den PHP-Code für die Navigation auf jeder Seite des Fragebogens, z.B. oben auf jeder Seite. Nachfolgend ein Beispiel, wie der PHP-Code dafür aussehen könnte:

<code php>
html(
  // Ein <div> sorgt für die optische Abgrenzung zwischen Navigation und Seiteninhalt
  '<div style="border: 2px solid #CCCCCC; border-left: 0 none; border-right: 0 none; padding: 20px 0 12px 0; margin-bottom: 3em;">'.
  // Ein weiteres <div> erlaubt die flexible Anordnung der Navigations-Schaltflächen
  '<div class="s2flex navButtons" style="flex-wrap: wrap; margin-right: -8px">'.NL.
  buttonToPage('start').
  buttonToPage('kontakt').
  buttonToPage('studium').
  buttonToPage('leistungen').
  buttonToPage('dokumente').
  buttonToPage('notizen').
  '<div style="width: 2em;"></div>'.
  buttonToPage('abschicken').
  '</div>'.
  '</div>'
);
</code>

Möchte man die Knöpfe noch ein wenig ansprechender gestalten, kann man im **Fragebogen-Layout** in der //HTML-Vorlage// im ''<style>''-Bereich noch ein wenig CSS-Code ergänzen:

<code css>
div.navButtons button {
  border: 2px solid %color.4%;
  border-radius: 5px;
  padding: 7px 6px;
  margin-bottom: 8px;
  flex-grow: 1;
  margin-right: 8px;
}
div.navButtons button.currentPage {
  background-color: %color.4%;
  color: white;
}
</code>


===== Mehrsprachige Beschriftung =====

In einem mehrsprachigen Fragebogen ([[:de:create:multilang]]) müssen die Beschriftungen der Knöpfe je nach Sprachversion angepasst werden. Dafür kann dem zweiten Parameter ein Array übergeben werden.

Ermitteln Sie unter **Sprachversionen** zunächst, welchen (dreistelligen) Code die verwendeten Sprachen haben. Das folgende Beispiel verwendet unterschiedliche Beschriftungen für die Sprache "Deutsch (Sie)", Code "ger" und "Englisch", Code "eng".

<code php>

<code php>
html(
  '<div style="text-align: center; margin: 2em 0">'.
  buttonToPage('early', array(
    'ger' => 'Zurück zur Auswahl',
    'eng' => 'Back to Selection'
  )).
  '</div>'
);
</code>

Dieselbe Konstruktion ist auch mit Platzhaltern möglich (die drei Schreibweisen demonstrieren lediglich, wie Sie den PHP-Code je nach Geschmack auf mehrere Zeilen verteilen können).

<code php>
buttonToPage('chapter1', array('ger' => 'Kapitel 1', 'eng' => 'Chapter 1'), '%btnC1%');

buttonToPage('chapter2', array(
  'ger' => 'Kapitel 2',
  'eng' => 'Chapter 2'
), '%btnC2%');

buttonToPage(
  'chapter3',
  array(
    'ger' => 'Kapitel 3',
    'eng' => 'Chapter 3'
  ),
  '%btnC3%'
);
</code>